<?php
/*
 * Copyright (c) 2008 Sergey Bondari, bondari@bondari.net
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * - Redistributions of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
 * - Redistributions in binary form must reproduce the above copyright
 *   notice, this list of conditions and the following disclaimer in the
 *   documentation and/or other materials provided with the distribution.
 * - The name of the author may not be used to endorse or promote products
 *   derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

namespace Mosaic\System;


/**
 * Event representation
 *
 * Generic event class. 
 * Event implements basic functionality as set/get variable and
 * implementation of ifEvent interface. Also event implements cancellation mechanism, i.e.
 * event should not be passed to the next recipient and returned to the invocator.
 *
 * @package System
 * @subpackage Resources
 */
class Event extends Resource implements ifEvent {
	/**
	 * Variables pool
	 * @var array Array of mixed
	 */
	private $vars;


	/**
	 * Event name
	 * @var string
	 */
	private $name;

	/**
	 * Event cancellation flag.
	 *	
	 * @var bvoolean True when event is ca
	 */
	private $cancelled;

	/**
	 * Constructor
	 * Gets an event name as parameter.
	 *
	 * @param string Name of the event
	 */
	function __construct($name) {
		parent::__construct();
		$this->cancelled = false;
		$this->name = $name;
		$this->callbacks = new \SplStack();
		$this->vars = array();
	}


	/**
	 * Event name getter.
	 * Returns the event's name.
	 * @return string Event's name
	 */
	public function getName() {
		return $this->name;
	}


	/**
	 * Event cancellation routine.
	 * Event handler needs to call cancel event to prevent further event propagation to other components 
	 * resulting in immediate return of the event to the invocating component.
	 */
	public function cancel() {
		$this->cancelled = true;
	}
	

	/**
	 * Event cancellation flag check
	 * @return boolean
	 */
	public function isCancelled() {
		return $this->cancelled == true;
	}
	/**
	 * Sets a variable value
	 * @param string variable name
	 * @param mixed variable value
	 */
	public function setVar($key, $val) {
		$this->vars[$key] = $val;
	}

	/**
	 * Returns a variable value
	 * @param string variable name
	 * @return mixed variable value
	 */
	public function getVar($key) {
		return array_key_exists($key, $this->vars) ? $this->vars[$key] : NULL;
	}



	/**
	 * Variable existence check
	 * @param string variable name
	 * @return boolean null status
	 */
	public function isNull($key) {
		return !array_key_exists($key, $this->vars);
	}

	/**
	 * String conversion handler.
	 * Returns an event name
	 * @return string event name
	 */
	public function __toString() {
		return $this->name;
	}


	/**	
	 * Events uniting.
	 * Used in aynchronous boomerang events functionality when event is delivered simultaneously to many components
	 * This trivial event uses array_merge function to merge variables of both events
	 *
	 * @param Event Event to merge with
	 * @return void
	 */
	public function merge($res) {
		if ($res->isCancelled()) $this->cancel();
		$this->vars = array_merge($this->vars, $res->vars);
	}


	/**	
	 * Resource serialization implementation
	 * @return string Serialzied event data
	 */
	public function __serialize() {
		return serialize($this);
	}


	/**	
	 * Resource deserialization implementation
	 * @return Event
	 */
	static public function __deserialize($string) {
		return unserialize($string);
	}
}
